1 /*
2 * Copyright (C) 2008 The Guava Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package com.google.common.collect;
18
19 import com.google.common.annotations.GwtCompatible;
20 import com.google.common.base.Objects;
21
22 import java.util.Collection;
23 import java.util.Map;
24 import java.util.Set;
25
26 import javax.annotation.Nullable;
27
28 /**
29 * A collection that associates an ordered pair of keys, called a row key and a
30 * column key, with a single value. A table may be sparse, with only a small
31 * fraction of row key / column key pairs possessing a corresponding value.
32 *
33 * <p>The mappings corresponding to a given row key may be viewed as a {@link
34 * Map} whose keys are the columns. The reverse is also available, associating a
35 * column with a row key / value map. Note that, in some implementations, data
36 * access by column key may have fewer supported operations or worse performance
37 * than data access by row key.
38 *
39 * <p>The methods returning collections or maps always return views of the
40 * underlying table. Updating the table can change the contents of those
41 * collections, and updating the collections will change the table.
42 *
43 * <p>All methods that modify the table are optional, and the views returned by
44 * the table may or may not be modifiable. When modification isn't supported,
45 * those methods will throw an {@link UnsupportedOperationException}.
46 *
47 * <p>See the Guava User Guide article on <a href=
48 * "http://code.google.com/p/guava-libraries/wiki/NewCollectionTypesExplained#Table">
49 * {@code Table}</a>.
50 *
51 * @author Jared Levy
52 * @param <R> the type of the table row keys
53 * @param <C> the type of the table column keys
54 * @param <V> the type of the mapped values
55 * @since 7.0
56 */
57 @GwtCompatible
58 public interface Table<R, C, V> {
59 // TODO(jlevy): Consider adding methods similar to ConcurrentMap methods.
60
61 // Accessors
62
63 /**
64 * Returns {@code true} if the table contains a mapping with the specified
65 * row and column keys.
66 *
67 * @param rowKey key of row to search for
68 * @param columnKey key of column to search for
69 */
70 boolean contains(@Nullable Object rowKey, @Nullable Object columnKey);
71
72 /**
73 * Returns {@code true} if the table contains a mapping with the specified
74 * row key.
75 *
76 * @param rowKey key of row to search for
77 */
78 boolean containsRow(@Nullable Object rowKey);
79
80 /**
81 * Returns {@code true} if the table contains a mapping with the specified
82 * column.
83 *
84 * @param columnKey key of column to search for
85 */
86 boolean containsColumn(@Nullable Object columnKey);
87
88 /**
89 * Returns {@code true} if the table contains a mapping with the specified
90 * value.
91 *
92 * @param value value to search for
93 */
94 boolean containsValue(@Nullable Object value);
95
96 /**
97 * Returns the value corresponding to the given row and column keys, or
98 * {@code null} if no such mapping exists.
99 *
100 * @param rowKey key of row to search for
101 * @param columnKey key of column to search for
102 */
103 V get(@Nullable Object rowKey, @Nullable Object columnKey);
104
105 /** Returns {@code true} if the table contains no mappings. */
106 boolean isEmpty();
107
108 /**
109 * Returns the number of row key / column key / value mappings in the table.
110 */
111 int size();
112
113 /**
114 * Compares the specified object with this table for equality. Two tables are
115 * equal when their cell views, as returned by {@link #cellSet}, are equal.
116 */
117 @Override
118 boolean equals(@Nullable Object obj);
119
120 /**
121 * Returns the hash code for this table. The hash code of a table is defined
122 * as the hash code of its cell view, as returned by {@link #cellSet}.
123 */
124 @Override
125 int hashCode();
126
127 // Mutators
128
129 /** Removes all mappings from the table. */
130 void clear();
131
132 /**
133 * Associates the specified value with the specified keys. If the table
134 * already contained a mapping for those keys, the old value is replaced with
135 * the specified value.
136 *
137 * @param rowKey row key that the value should be associated with
138 * @param columnKey column key that the value should be associated with
139 * @param value value to be associated with the specified keys
140 * @return the value previously associated with the keys, or {@code null} if
141 * no mapping existed for the keys
142 */
143 V put(R rowKey, C columnKey, V value);
144
145 /**
146 * Copies all mappings from the specified table to this table. The effect is
147 * equivalent to calling {@link #put} with each row key / column key / value
148 * mapping in {@code table}.
149 *
150 * @param table the table to add to this table
151 */
152 void putAll(Table<? extends R, ? extends C, ? extends V> table);
153
154 /**
155 * Removes the mapping, if any, associated with the given keys.
156 *
157 * @param rowKey row key of mapping to be removed
158 * @param columnKey column key of mapping to be removed
159 * @return the value previously associated with the keys, or {@code null} if
160 * no such value existed
161 */
162 V remove(@Nullable Object rowKey, @Nullable Object columnKey);
163
164 // Views
165
166 /**
167 * Returns a view of all mappings that have the given row key. For each row
168 * key / column key / value mapping in the table with that row key, the
169 * returned map associates the column key with the value. If no mappings in
170 * the table have the provided row key, an empty map is returned.
171 *
172 * <p>Changes to the returned map will update the underlying table, and vice
173 * versa.
174 *
175 * @param rowKey key of row to search for in the table
176 * @return the corresponding map from column keys to values
177 */
178 Map<C, V> row(R rowKey);
179
180 /**
181 * Returns a view of all mappings that have the given column key. For each row
182 * key / column key / value mapping in the table with that column key, the
183 * returned map associates the row key with the value. If no mappings in the
184 * table have the provided column key, an empty map is returned.
185 *
186 * <p>Changes to the returned map will update the underlying table, and vice
187 * versa.
188 *
189 * @param columnKey key of column to search for in the table
190 * @return the corresponding map from row keys to values
191 */
192 Map<R, V> column(C columnKey);
193
194 /**
195 * Returns a set of all row key / column key / value triplets. Changes to the
196 * returned set will update the underlying table, and vice versa. The cell set
197 * does not support the {@code add} or {@code addAll} methods.
198 *
199 * @return set of table cells consisting of row key / column key / value
200 * triplets
201 */
202 Set<Cell<R, C, V>> cellSet();
203
204 /**
205 * Returns a set of row keys that have one or more values in the table.
206 * Changes to the set will update the underlying table, and vice versa.
207 *
208 * @return set of row keys
209 */
210 Set<R> rowKeySet();
211
212 /**
213 * Returns a set of column keys that have one or more values in the table.
214 * Changes to the set will update the underlying table, and vice versa.
215 *
216 * @return set of column keys
217 */
218 Set<C> columnKeySet();
219
220 /**
221 * Returns a collection of all values, which may contain duplicates. Changes
222 * to the returned collection will update the underlying table, and vice
223 * versa.
224 *
225 * @return collection of values
226 */
227 Collection<V> values();
228
229 /**
230 * Returns a view that associates each row key with the corresponding map from
231 * column keys to values. Changes to the returned map will update this table.
232 * The returned map does not support {@code put()} or {@code putAll()}, or
233 * {@code setValue()} on its entries.
234 *
235 * <p>In contrast, the maps returned by {@code rowMap().get()} have the same
236 * behavior as those returned by {@link #row}. Those maps may support {@code
237 * setValue()}, {@code put()}, and {@code putAll()}.
238 *
239 * @return a map view from each row key to a secondary map from column keys to
240 * values
241 */
242 Map<R, Map<C, V>> rowMap();
243
244 /**
245 * Returns a view that associates each column key with the corresponding map
246 * from row keys to values. Changes to the returned map will update this
247 * table. The returned map does not support {@code put()} or {@code putAll()},
248 * or {@code setValue()} on its entries.
249 *
250 * <p>In contrast, the maps returned by {@code columnMap().get()} have the
251 * same behavior as those returned by {@link #column}. Those maps may support
252 * {@code setValue()}, {@code put()}, and {@code putAll()}.
253 *
254 * @return a map view from each column key to a secondary map from row keys to
255 * values
256 */
257 Map<C, Map<R, V>> columnMap();
258
259 /**
260 * Row key / column key / value triplet corresponding to a mapping in a table.
261 *
262 * @since 7.0
263 */
264 interface Cell<R, C, V> {
265 /**
266 * Returns the row key of this cell.
267 */
268 R getRowKey();
269
270 /**
271 * Returns the column key of this cell.
272 */
273 C getColumnKey();
274
275 /**
276 * Returns the value of this cell.
277 */
278 V getValue();
279
280 /**
281 * Compares the specified object with this cell for equality. Two cells are
282 * equal when they have equal row keys, column keys, and values.
283 */
284 @Override
285 boolean equals(@Nullable Object obj);
286
287 /**
288 * Returns the hash code of this cell.
289 *
290 * <p>The hash code of a table cell is equal to {@link
291 * Objects#hashCode}{@code (e.getRowKey(), e.getColumnKey(), e.getValue())}.
292 */
293 @Override
294 int hashCode();
295 }
296 }